home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / ansi / txtcap20.zip / TEXTCAP.DOC < prev   
Text File  |  1991-12-05  |  9KB  |  207 lines
  1.  
  2.  
  3.  
  4.                           T E X T C A P  1 . 0
  5.                           ====================
  6.  
  7.                        TapirSoft Gisbert W.Selke
  8.  
  9.                                 Dec 1991
  10.  
  11.  
  12. General Overview
  13. ================
  14.  
  15. TextCap provides you with the possibility to capture text screens to
  16. to your disk. The output is written with both text and display-attribute
  17. bytes, so that no information is lost. However, this format is ugly to
  18. read (or to incorporate into ordinary text); hence, a companion
  19. programme allows to extract the plain text out of a captured file.
  20.  
  21. Basic Instructions
  22. ==================
  23.  
  24. The simplest way to run TextCap is to invoke it from the DOS command
  25. line just like that:
  26.  
  27.                 textcap
  28.  
  29. TextCap will install itself in memory with default values (cf. below)
  30. and wait for you to trigger it. You may now enter your (text mode)
  31. application, and whenever your screen shows text you want to save, hit
  32. the hot key, by default Ctrl-F9. TextCap will then write the text
  33. screen, complete with attribute bytes which tell about colours and so
  34. forth, to a file named SCN00000.TXT in the current directory, which
  35. takes a few moments, depending on the speed of your disk.
  36.  
  37. The next time you want to save some text, press Ctrl-F9 again, and a
  38. new file named SCN00001.TXT will be written to the current directory,
  39. and so on.
  40.  
  41. After exiting your text application, you could view this text by, e.g.,
  42. typing it. However, you probably won't be able to make much sense out of
  43. the attribute bytes which alternate with the text bytes. They are there
  44. just so that no information is lost, and so that you can use them if you
  45. want to. For most purposes, you will want to extract the text only,
  46. properly formatted at (by default) 80 columns per line. You do this by
  47. typing
  48.  
  49.                 scn2asc  < scn00000.txt > scn00000.lst
  50.  
  51. for the first of the screens captured; of course, the first parameter
  52. can be replaced by the name of any captured file. The second name is
  53. really arbitrary; you could have, e.g., "foo.bar" after the ">"
  54. character, if you so wished. Just make sure it's not the same as the
  55. name of the file you want to convert!
  56.  
  57. If, for reasons unknown, you ever have different size text screens,
  58. TextCap will handle these as well, up to a size of 132 columns and 50
  59. lines. In this case, however, you should inform Scn2Asc about this fact,
  60. so that line-wrap is handled properly. You do so by mentioning the
  61. desired number of columns per line on the command line; e.g., for
  62. a 132-column screen,
  63.  
  64.                 scn2asc  < scn00001.txt > scn00001.lst 132
  65.  
  66. TextCap will remain in memory until you re-boot, so you may enter your
  67. text application (or any other one) again and again without having to
  68. run TextCap again.
  69.  
  70. Note that the TXT files are always written to the current directory,
  71. unless you have explicitly requested otherwise (cf. below); the number
  72. part of the name, however, will be incremented even if you have changed
  73. directories in the meantime. TextCap will never overwrite an existing
  74. file, though.
  75.  
  76.  
  77. Optional arguments
  78. ==================
  79.  
  80. The behaviour of TextCap may be changed on the command line by a few
  81. optional arguments, to wit:
  82.  
  83. /?      : display list of available arguments; do not install
  84. /P<path>: Use the path given instead of the current directory. This
  85.           ensures that you'll find all your graphics dumps in one place,
  86.           even if you change directories wildly. You should use absolute
  87.           paths (i.e., as seen from the root directory) and drive
  88.           specifier, to make sure. (Don't type the angle brackets!)
  89. /K<xxxx>: Use a different hot key specified by the 4 hex digits <xxxx>
  90.           (again, don't type the angle brackets!). The default is 4309
  91.           for Ctrl-F9. If you specify /K?, you will be prompted to hit a
  92.           key; TextCap will not install itself but show the hex number
  93.           that this key corresponds to.
  94. /U      : Uninstall TextCap, i.e., tell TextCap to remove itself from
  95.           memory. You may want to do this when you're sure you no longer
  96.           need TextCap for a while; it will return a considerable chunk
  97.           of memory to DOS and your other programmes.
  98.  
  99.  
  100. As an example, if you want TextCap to write the text file to your RAM
  101. disk E: and to trigger whenever you type Ctrl-Alt-P, you should use
  102.  
  103.                 textcap /pe: /k1908
  104.  
  105. Note that there are no blanks between "/p" and the path, and between
  106. "/k" and the number.
  107.  
  108. To remove TextCap later, type
  109.  
  110.                 textcap /u
  111.  
  112. There is no way to change the parameters once TextCap has been started;
  113. so, if you discover you want to change one of the parameters later, you
  114. have to remove TextCap using the "/u" argument and install it anew.
  115.  
  116.  
  117. Application Programmer's Interface (API)
  118. ========================================
  119.  
  120. TextCap has a very simple interface, if you want to call it from a
  121. programme of yours, instead of from the DOS command line or via hot key.
  122. First, you must install TextCap as usual; then, you can call interrupt
  123. 16h with a value of 4252h in register ax. If, on return, ax contains
  124. 5242h, then TextCap is resident; otherwise it isn't. Once you know it's
  125. there, you can call interrupt 16h with ax=4254h to cause an immediate
  126. screen capture - just as if you had typed the hot key.
  127.  
  128. The last thing - and a somewhat dangerous thing at that - you can do is
  129. call interrupt 16h with ax=4253h. This requests removal of TextCap from
  130. memory; actually, it just disables all services by returning all the
  131. intercepted interrupts. TextCap then returns control to your programme,
  132. with the segment at which it was loaded returned in ax. Your programme
  133. is responsible for deallocating that memory. Also, your programme should
  134. *not* have hooked any of the interrupts that were used by TextCap -
  135. otherwise, havoc will ensue. To sum it up, this function call should
  136. probably not be made by your programme, unless you know what you're
  137. doing.
  138.  
  139.  
  140. Possible Problems
  141. =================
  142.  
  143. TextCap uses about 14 KB of main DOS memory. This should rarely be a
  144. problem. If, however, the text application you wanted TextCap for runs
  145. fine with TextCap in memory, but a different programme needs more memory
  146. (say, some word processor), you can easily reclaim memory by removing
  147. TextCap from memory as soon as you're finished capturing.
  148.  
  149. Note that, due to the design of DOS, memory is *not* freed up if another
  150. resident utility has been loaded *after* TextCap. In this case, you
  151. should first remove that utility and then proceed to uninstalling
  152. TextCap.
  153.  
  154. A common conflict arises from hot key usage. If your application acts on
  155. Ctrl-F9, you won't be able to perform this action anymore. Unles... you
  156. tell TextCap what other hot key to use! Find a key that is not used for
  157. any other purpose, and restart TextCap with a different hot key
  158. assignment (cf. above). (Remember you have to uninstall TextCap if it's
  159. already loaded!)
  160.  
  161. Restrictions
  162. ============
  163.  
  164. TextCap uses some 14 KB memory, which is noticeable. The reason is that
  165. a complete screen (of up to 132*50 characters plus their attributes) is
  166. stored in memory before it is written out to disk. This, in turn, is
  167. necessitated by DOS not being re-entrant.
  168.  
  169. TextCap uses neither extended nor expanded memory. If interest warrants,
  170. such a feature will be included in a future release... maybe.
  171.  
  172. TextCap hooks into interrupts 09h, 13h, 16h, and 21h. It is, however,
  173. 'well-behaved'; i.e, it interferes only as far as is unavoidable. This
  174. means it will not pass along the hot key, and it also reserves int 16h
  175. calls with ax=4252h, ax=4253h, and ax=4254h, which should be no problem
  176. at all. - Some memory mappers report that TextCap also hooks interrupts
  177. CFh and F0h; this seems to be an artifact, as TextCap definitely does
  178. *not* touch these vectors that are purported to be used by DOS's BASIC
  179. interpreter.
  180.  
  181. TextCap will handle errors during writing to disk only so-so. In
  182. particular, a full disk leads to a partial text file that will perhaps
  183. be unusable. Also, if you write to your disk's root